Full delegation (user choice) replaces all three inline uses of the
standard; D4 rescoped, D5 gains opt-in dependency fallback, D7 expands
to the full docs/tooling inventory; 11 findings recorded.

Resolve dead spec anchors, add missing inline D1/D5 links, complete
cross-reference fields on all decisions and findings.

…ndency

Every plugin that hosts or triggers a delegating skill (han-core,
han-coding, han-github, han-reporting, han meta, han-atlassian) declares
han-communication directly; no transitive-resolution reliance. Closes
OI-1 and cleans up han-planning exclusion wording.

…findings

Team (junior-developer, adversarial-validator, evidence-based-investigator,
gap-analyzer) confirmed the plan's foundations and surfaced: step-order
preservation risk under forced delegation (D4), dependency-graph narration
scope (D7 class 5), manifest description updates (D8), the Codex packaging
surface (new D10), plus delegation-scope wording and future-wrapper rule.

…me doc scope

Resolve 9 findings: split Preconditions for the Codex surface (F23),
widen D4's step-preservation commitment to renumber/split/heading cases
(F28), qualify D10 Codex parity + opt-in install path + OI-2 (F29), and
reframe D7 doc classes as a comprehensive grep so the recurring
missed-file class is closed (F25-F27, F30, F31).

Final round (Large cap): junior-developer clean; adversarial-validator
reproduced the D5/D10 inventories and confirmed no file-discovery gap.
Resolved 4 refinements (F32-F35): rewrite-depth for docs/readability.md,
order-significant non-numbered lists in the preservation commitment,
OI-2 blast-radius correction, and the mandated Review History section.

…guidance skill)

Adopt the readability-guidance skill approach after evidence gathering
(Claude Code docs + in-repo): skills invoked via the Skill tool run in
the same context, so han-communication exposes a resource-surfacing
readability-guidance skill that sources the standard cross-plugin for
in-voice drafting. D3 reframed (source cross-plugin), D4 reframed (staged
model, editor retained for synthesis only), D11 added (the guidance
mechanism), OI-3 added (prototype gate). Preserves docs/readability.md's
staged model that full delegation collapsed; rehabilitates the F3 hybrid.

…ated

Adversarial R4 found readability-guidance is the repo's documented
data-fetch composition anti-pattern (skill-composition.md). Per user
direction (option 3): built and ran an inline prototype (resumed 3/3 —
weak signal, not reliability), did NOT update skill-composition.md,
hardened OI-3 into a rigorous blocking spike with a named fallback, and
captured the risk + inline-vs-fork distinction on D11. Fixed revision
propagation: stale D7 'abolished staged model' (F36), editor rule-path
break (F37), impossible edge-case examples (F40), decision counts (F43),
and refreshed the Review History for R4.

…ualified

Rigorous subagent-harness spike (46 trials, 4 arms): 34/34 same-context
Skill-call invocations completed with zero early exits, including a
worst-case adversarial arm. Forked context:fork disqualified because it
isolates the guidance so its content never reaches the caller. api_retry
could not be induced (infra-level fault), so that path is reduced by
inference, not measured. D11 known-risk resolved and prototype gate
cleared; skill-composition.md to record the inline variant as a
supported exception.

Records the spike outcome in the spec: OI-3 marked resolved, the inline
readability-guidance mechanism validated (34/34 same-context runs, zero
early exits) and the forked variant disqualified. Bakes the inline (no
context:fork) requirement into the Primary Flow, updates the open-item
count 2 -> 1, and notes the unmeasured api_retry residual risk plus the
documented fallbacks.

…ption

The OI-3 spike validated one narrow shape that looks like data-fetch but
is supported: an inline (never context:fork) sub-skill that surfaces a
whole shared standard into the caller's context and hands control back.
Carves it out of the data-fetch section with its three defining
properties, adds it to the decision guide, and keeps the honest limit
that api_retry was not directly exercised.

Move the spike report, incident fixture, all 46 trial artifacts, and the
8 harness skill definitions from the session scratchpad into
artifacts/oi-3-spike/ so the spike is reproducible independent of the
session that ran it. Add a pointer from the research note.

…anic graduated to T1

Lightweight self-review round confirming the post-spike edits are
internally consistent (open-item count, trial counts, cross-file claims
all agree). One finding (F46): the OI-3 edit had leaked the context:fork
frontmatter mechanic into a Primary Flow behavioral sentence. Since the
spike settled that mechanic, it graduates from the OI-3 open item to a
new technical note T1; Primary Flow restated behaviorally. No blocking
open items remain (OI-2 non-blocking); spec ready for plan-implementation.

…ation)

Medium team (PM + junior-developer + structural-analyst + devops-engineer
+ test-engineer), 2 rounds. Produces feature-implementation-plan.md plus
the implementation decision log (8 full + 1 trivial decision) and
iteration history, and a discovery-notes inventory.

Key outcomes: 6-phase copy-first/delete-last sequencing with a hard
pre-delete grep gate; the exact 6-plugin direct-dependency edge list
(confirming D5 from scratch); editor invocation-contract change (rename +
drop rule-path arg); the Codex surface is EXTENDED not built (RECON-1),
with zero Codex dependency/description edits; version bumps listed but
deferred to release (han-core a MAJOR candidate); a grep-driven docs
sweep including the 'agents live in han-core' exception; manual
verification (static grep/diff + one light smoke, no CI). 3 YAGNI
deferrals. Open items OI-2 and the semver call are both non-blocking.

…(Phase 1)

Stand up the new han-communication plugin additively — the suite still runs on
the existing vendored copies until later phases rewire and delete them.

- Both manifests: .claude-plugin/plugin.json (no dependencies) and
  .codex-plugin/plugin.json mirroring han-core's Codex schema
- Co-located canonical references/readability-rule.md + writing-voice.md
- readability-editor agent and edit-for-readability skill (byte copies)
- New inline readability-guidance skill (no context: fork) that surfaces the
  standard into the caller's context
- han-communication entries added to both marketplaces

Refs feature-implementation-plan.md D-4, D-7, T1.

…e 2)

Add the han-communication dependency edge to the six declaring Claude
manifests before any consumer rewire, so the capability resolves by qualified
name once Phase 3 lands.

- han-core gains its first-ever dependencies key (["han-communication"])
- han-coding, han-github, han-reporting prepend han-communication
- han meta and han-atlassian prepend han-communication
- Update dependency-narrating descriptions for han, han-coding, han-atlassian
  in both plugin.json and the marketplace.json mirror
- han-planning, han-linear, han-feedback, han-plugin-builder untouched
- Zero Codex edits (schema has no dependencies field)

Refs feature-implementation-plan.md D-1, D-4.

…s-plugin (Phase 3)

All 13 consumer skills now source the shared readability standard by invoking
han-communication:readability-guidance at their drafting point instead of
reading a vendored ../../references/readability-rule.md file.

- 9 synthesis skills: editor dispatch renamed han-core -> han-communication and
  the now-unresolvable rule-path argument dropped (the editor reads its own
  co-located canonical rule); gap-analysis's size-conditional skip preserved
- 4 draft-and-self-check skills (runbook, issue-triage, ADR, html-summary):
  gain the guidance invocation, dispatch no editor
- edit-for-readability (han-communication copy): editor rename + rule-path drop
- self-check lead-ins repointed to the in-context standard; the six criteria
  blocks are unchanged
- 6 secondary template/reference files repointed off the dead rule path

Refs feature-implementation-plan.md D-3.

…s (Phase 4)

With every consumer rewired and the pre-delete grep gate clean, remove the
duplicated readability capability so han-communication owns the only copy.

- 6 vendored references deleted (han-coding, han-github, han-reporting x
  readability-rule.md + writing-voice.md)
- 4 han-core originals deleted (readability-editor agent, edit-for-readability
  skill, readability-rule.md, writing-voice.md)
- find now returns exactly one copy of each reference file
- no han-core:readability-editor / han-core:edit-for-readability name survives
  in plugin source

Refs feature-implementation-plan.md D-2.

…ove (Phase 5)

Repoint every doc, index, and dependency narration at the new han-communication
home and reframe the invariants the move inverts.

- Move long-form docs: readability-editor -> docs/agents/han-communication/,
  edit-for-readability -> docs/skills/han-communication/; fix their sibling links
- New readability-guidance long-form doc, with the api_retry residual-risk
  troubleshooting note
- Skills index gains a foundational han-communication section (readability-guidance
  + edit-for-readability); agents index entry repointed
- Reframe "all agents live in han-core" to name the han-communication exception
  (CLAUDE.md, CONTRIBUTING.md); record han-core's first-ever dependency
- Replace the vendoring instruction with cross-plugin sourcing via
  readability-guidance (CONTRIBUTING.md, docs/readability.md)
- Repoint canonical readability-rule.md / writing-voice.md pointers, dependency
  narration (README, choosing-a-han-plugin, extend-han how-to), and the
  han-atlassian Codex co-requisite; add han-communication to both install lists
- Repoint live .claude/ maintenance skills and the PR template at the new
  writing-voice.md location
- CHANGELOG Unreleased entry records the extraction; history left untouched

Refs feature-implementation-plan.md D-6, D-7, D-9.

The lint workflow added in #120 surfaced three pre-existing failures. This
commit fixes the two shellcheck findings and the broken symlink.

- init-guidance.sh: the first sed expression matches the literal text
  "${CLAUDE_PLUGIN_ROOT}" as it appears in the vendored SKILL.md, so the
  single quotes are required and SC2016 is a false positive. Disable the
  check at that call with a comment explaining why.

- upload-screenshots.sh: verify_on's retry loop never reads its counter, so
  SC2034 fired on it. Use the conventional throwaway `_` instead.

- .claude/rules/plugin-entity-taxonomy.md: the symlink still pointed at
  docs/guidance/, which ad6ee13 moved to
  han-plugin-builder/skills/guidance/references/. That commit rewrote the
  adjacent .claude/rules/ text references but could not catch a symlink
  target. Repoint it at the file's current home.

The lint workflow added in #120 runs Prettier over all files, but the repo
had never been formatted with it, so the hook rewrote 279 files and failed
the job. This commit lands that formatting so the hook is a no-op.

Formatting only: prose is rewrapped to the 120-column width set in
.prettierrc.json, emphasis markers are normalized, and table cells are
padded. No prose was changed. The one non-whitespace change is in
han-coding/skills/coding-standard/SKILL.md, where an ordered list was
misnumbered 1, 2, 4, 5; Prettier owns ordered-list numbering per
.pre-commit-config.yaml and renumbered it to 1, 2, 3, 4.

# Conflicts:
#	han-atlassian/.claude-plugin/plugin.json
#	han-coding/.claude-plugin/plugin.json
#	han-github/.claude-plugin/plugin.json
#	han-plugin-builder/skills/guidance/scripts/init-guidance.sh
#	han-reporting/.claude-plugin/plugin.json
#	han/.claude-plugin/plugin.json

…d consolidating guidance (#114)

140+ files, and +4K/-1K ... 😭 this may be the cause of a Han v5 release.
still a WIP though. needs a lot of testing and fine tuning first.

that said ...

---

## Summary

**This PR extracts Han's readability standard into a new foundational
`han-communication` plugin that every prose-producing plugin depends on,
so the writing rule and voice profile live in one canonical place
instead of being copy-pasted into each plugin.**

## Behavior changes

The readability standard now has a single owner. Before this branch,
`readability-rule.md` and `writing-voice.md` were vendored into
`han-core`, `han-github`, and `han-reporting`. "Vendored" means the same
files were duplicated on disk. Editing the standard meant editing
several copies and hoping they stayed in sync. Now the two files live
only in `han-communication/references/`, the duplicates are deleted, and
there is one source of truth.

Consuming skills reach the standard through a new inline skill,
`han-communication:readability-guidance`. "Inline" means it runs in the
calling skill's own context rather than in a separate agent. It reads
the two canonical reference files and hands control straight back, so
the standard stays loaded while the caller drafts and self-checks.
Rewired skills (`code-review`, `research`, `update-pr-description`,
`stakeholder-summary`, and others) now invoke that skill instead of
reading a vendored copy. The `readability-editor` agent and the
`edit-for-readability` skill also moved into `han-communication`. The
adversarial rewrite pass they perform is unchanged.

For anyone installing the suite, `han-communication` is a new dependency
edge beneath everything. The `han` meta-plugin now bundles it, and
`han-core`, `han-coding`, `han-github`, `han-reporting`, and the opt-in
`han-atlassian` each declare a direct dependency on it. This is
`han-core`'s first-ever dependency. Installing any prose-producing
plugin now pulls in `han-communication` automatically.

## What to look at first

1. Start with `han-communication/skills/readability-guidance/SKILL.md`.
It holds the new inline skill and the mechanism the whole PR turns on.
Confirm that the "runs in the caller's context, does not produce a
deliverable" contract reads clearly, since every consumer now depends on
that behavior.
2. Check the dependency edges in the `plugin.json` manifests and
`.claude-plugin/marketplace.json`. Verify that the new
`han-communication` dependency is declared on each prose-producing
plugin and that the meta-plugin bundles it, so no consumer sources the
standard without depending on its owner.
3. Read one or two rewired consumer `SKILL.md` files, for example
`han-core/skills/research/SKILL.md` and
`han-github/skills/update-pr-description/SKILL.md`. Check that the
cross-plugin invocation replaces the old vendored read cleanly and that
nothing still points at a deleted copy.
4. Compare the Phase 4 deletions (`git show 563efec --stat`) against the
Phase 3 rewiring. Confirm that every vendored copy that was removed had
its consumers repointed first, so no skill is left reading a file that
no longer exists.

…le 5)

…ill's candidate pool

…ers so temp files outrank the configured base

…d pointer to .han/config.md

…from concepts, quickstart, and CLAUDE.md

… when the file is absent

…loads survive an absent config

## Summary

**This PR adds project-local Han configuration through an optional
`.han/config.md` file, so a consuming project can redirect where skills
write their deliverables and name extra agents for dispatching skills to
consider, without editing the plugins.**

## Behavior changes

A consuming project can now carry one optional file, `.han/config.md`,
that adjusts how Han skills behave in that project.

It supports two overrides. An `output-directory` frontmatter key sets a
base directory where skills write their markdown deliverables, keeping
their own folder structure beneath it. An `## Extra Agents` section
names additional agents that dispatching skills weigh alongside their
built-in rosters.

Every skill with a `## Project Context` block reads the file through an
inline probe. A project with no config file behaves exactly as before,
and it does so silently.

A new canonical rule file, `han-core/references/config-rule.md`, defines
how every skill interprets the config, so one file resolves identically
across the suite. It sets four contract points:

- A precedence chain: explicit input beats config beats CLAUDE.md beats
project-discovery beats defaults.
- A path-containment rule: `output-directory` must be a contained
relative path; absolute paths or `..` escapes fall back to the default
with a one-line note.
- A pool-join rule: config-named extra agents join each skill's existing
candidate pool under that skill's existing size caps.
- A degradation guarantee: a bad config is ignored with a one-line note,
never a failed run.

`project-discovery` gains a consent-gated step that offers to add or
remove a CLAUDE.md pointer to the config. `docs/configuration.md` is the
new operator guide.

Late on the branch, a probe bug surfaced, and this PR fixes it. The
probe originally shipped as `cat .han/config.md 2>/dev/null`, which
exits non-zero when the file is absent. That made Claude Code's loader
fail every skill run in the normal no-config case.

The fix now reads `cat .han/config.md 2>/dev/null || echo ""`, the
loader-allowlisted guard, applied across all 39 files. One live-loader
spot-run in a consuming project remains as a release check.

## What to look at first

1. `han-core/references/config-rule.md` is the whole behavioral contract
(precedence, path containment, pool-join, degradation). Read it first.
The 12 vendored copies are byte-identical, so reviewing one covers all.
2. The nine dispatching skills with bespoke pool-join edits (for example
`han-planning/skills/plan-a-feature/SKILL.md`) are where extra agents
compete for roster slots under each skill's caps. Check that the join
respects the size cap and skips unresolvable names.
3. The probe-guard fix and its investigation note under `docs/plans/`
explain why `|| echo ""` is load-bearing rather than cosmetic. This is
the one change that affects every no-config project.
4. The six `han-atlassian` wrappers pass explicit output paths so their
temp files outrank the configured base. Confirm that precedence
interaction reads correctly against the rule's chain.

…erpretation contract

…t sizing-aware skills

…record ADR 0001

…ze setting

)

## What

Adds the feature specification for a new `.han/config.md` frontmatter
setting, `default-swarm-size` (`small` | `medium` | `large` | `dynamic`,
absent = `dynamic`), which sets a standing default band for the eight
sizing-aware skills.

Planning artifacts (spec, decision log, team findings) live in
`docs/plans/config-default-swarm-size/`.

## Key behaviors specified

- A configured `small`/`medium`/`large` forces the band exactly like an
explicit size argument; explicit user input still wins under the
existing config precedence chain.
- `dynamic` (or no setting) keeps today's auto-classification, and
`dynamic` is also accepted as an explicit per-run size to override a
configured band for one run.
- An unrecognized size argument (typo) falls through to the config
instead of silently bypassing it.
- Unusable values degrade with the existing one-line note; a bad config
never fails a run.
- Doc surfaces in scope: config-rule.md (canonical + vendored copies),
docs/configuration.md, docs/sizing.md, plus an ADR recording the
reversal of the "sizing is overridable, not configurable" principle.

## Review

Reviewed at size Small by han-core:junior-developer and
han-core:edge-case-explorer; 13 findings recorded and resolved in
`artifacts/team-findings.md`. One open item: extend the manual test plan
(does not block implementation).

…dation

…stigation

…x dependency narration drift

…tation audit

- CLAUDE.md: add the missing docs/ entries (adr/, evidence, local-development,
  plugin-readme, readability, semantic-versioning, why-solo-and-small-teams)
  to the repository layout and fix a typo
- junior-developer: drop the stale claim that /code-overview dispatches it;
  the readability-editor pass replaced that review
- project-manager: add the missing /plan-work-items dispatcher link
- automated-test-planning, code-overview, manual-test-planning: bring the
  TL;DR sections back to the three one-sentence-bullet template shape
- runbook: replace an em-dash in an example prompt

…ts under plain-language categories

…lect leftovers under Other tests

…ests (#145)

## What this changes

The `manual-test-planning` skill now looks for a plain-language way to
categorize the tests whenever a plan holds more than five of them. When
a natural grouping covers every test, both **Tests at a Glance** and
**Test Details** are organized under the category names, with the same
categories and test order in both sections. When no grouping covers
every test, or the plan has five tests or fewer, the flat list stays.

## Files changed

- `han-coding/skills/manual-test-planning/SKILL.md` — Step 3 gains the
categorization rule (threshold, one category per test, plain-language
names, run order preserved, flat-list fallback); Step 4 tells the draft
to follow the template's categorized layout; Step 7 preserves category
names through the readability edit and adds a self-check that both
sections still share the same category structure; the frontmatter
description mentions the category behavior.
- `han-coding/skills/manual-test-planning/references/template.md` —
Tests at a Glance and Test Details each document the flat and
categorized layouts (categories as level-three headings, tests as
level-four headings in the details).
- `han-coding/docs/skills/manual-test-planning.md` — long-form doc
updated to match: key concepts, what you get back, and the step
walkthrough.

## Notes

- No version bump; versioning is left to the release process.
- Scent lines in the plugin README and skills index are unchanged; the
category behavior is a detail below the one-sentence scent.

…plan test and grouped layout

## Summary

Adds a new `writing-voice` frontmatter key to the `.han/config.md`
project config, letting a consuming project point Han's readability
surfaces at its own writing-voice profile instead of the built-in Han
voice.

## Behavior

- **Absent or blank**: the built-in profile at
`han-communication/references/writing-voice.md` applies, with no mention
of the config.
- **Set to a file that exists** (path relative to the working
directory): that file replaces the built-in profile wholesale for the
run, including the vocabulary blocklist the readability rule enforces.
- **Set to a file that does not exist**: the skill warns the user and
asks whether to use the built-in Han voice or skip the writing voice
entirely for the run. Skipping applies the readability rule with no
voice profile and no blocklist. This is an explicit, documented
exception to the config rule's silent note-and-degrade behavior.

## Changes

- `han-core/references/config-rule.md` (canonical): defines the
`writing-voice` key and names the ask-instead-of-note exception in the
degradation section. All vendored copies re-synced byte-identical.
- `han-communication:readability-guidance`: Step 1 now resolves the
voice source (configured file, warn-and-ask fallback, or built-in)
before reading the standard, so every prose-producing consumer picks the
override up automatically.
- `han-communication:edit-for-readability`: resolves the voice in Step 1
and carries the outcome (file path, skip instruction, or nothing) into
the readability-editor dispatch.
- `readability-editor` agent: accepts a named voice-profile file in
place of the built-in profile, or a skip instruction that drops only
blocklist enforcement.
- Docs: `docs/configuration.md` annotated example and new
`writing-voice` section (overview made count-free), plus matching
updates to the long-form docs for both skills and the agent.

…test plan